Shout3D™ 2.0 Specification
home previous
next contentsShout3D™ 2.0 Specification
|
|
Field Types and Field Usage Reference3.1 IntroductionFields store the data that parameterize nodes. Shout3D provides a set of twelve field types to store this data, described in 3.2, Field Types. Field usages describe how a node intends to use the data stored in a particular field. Shout3D provides a set of twenty two field usages, which describe the specialized ways that nodes in the Shout3D will interpret data in their fields. These are described in 3.3, Field Usages. The set of field usages may be extended as needed by those who write new nodes (see Creating New Usages). 3.2 Field TypesFields store the data that parameterize nodes. Each type of field stores either a single value or a one dimensional array of values of the same type. All nodes in Shout3D 2.0 use combinations of the fields shown in Table 3.1. Table 3.1 -- Field Types
3.3 Field Type DetailsThis section describes the kind of values stored in each type of field. 3.3.1 BooleanField and BooleanArrayFieldBooleanField specifies a single boolean value.
BooleanArrayField specifies zero or more boolean values.
Boolean values are 3.3.2 DoubleField and DoubleArrayFieldDoubleField specifies one double-precision floating point number. DoubleArrayField specifies zero or more such numbers. 3.3.3 FloatField and FloatArrayFieldFloatField specifies one single-precision floating point number. FloatArrayField specifies zero or more such numbers. 3.3.4 IntField and IntArrayFieldIntField specifies one 32-bit integer. IntArrayField specifies zero or more such numbers. 3.3.5 NodeField and NodeArrayFieldNodeField specifies a Shout3D node. NodeArrayField specifies zero or more nodes. The NodeField may 3.3.6 StringField and StringArrayFieldStringField and StringArrayField contain strings formatted with the UTF-8 universal character set (see [UTF8]). StringField specifies a single string. The StringArrayField specifies zero or more strings. Any characters may appear within the quotes. A double quote character within the string is preceded with a backslash. A backslash character within the string is also preceded with a backslash forming two backslashes. For example: "He said, \"Schnoobie is most nice!\"" 3.4 Field UsagesFields may be used for storing many different kinds of information. Although individual field types are not provided to handle every particular kind of information, each type of node does store an intended use for each of its fields. For example, a node might use a FloatArrayField to store any of a coordinate, a set of coordinates, a rotation, a set of rotations, etc. Knowledge of this intended use is needed to create customized interfaces for specialized editing, or to write algorithms (outside the core) to perform value-range checking and data compression. This intended use is referred to as a Field Usage. Note that in Shout3D, field usages are not enforced. They are provided for future developers that may wish to incorporate the information. For a given node class, a field will always have the same usage for all instances of that node class. Each field usage is described by its associated field type, valid value range, and number of values per element. The associated field type denotes the only kind of field that may be employed for a given field usage. (Example: Only a FloatArrayField may be used to store a COLOR). The exception to this is the field usage ANY, which may be used for any field type. The valid value range describes the allowable values for a given field usage. If the usage is ANY, then all possible values for the field are valid. In the case of NodeField and NodeArrayField, the valid value range denotes the type of nodes that may be used to fill that field. The number of values per element is relevant only when the associated field type is an array field; the term refers to how many values from the array comprise a single element for use. (Example: Both COLOR and COLOR_ARRAY use triples of floats, so for both, the number of values per element is 3). The set of Core field usages is in Table 3.2. Other field usages may be added, for use by new nodes that are created. In specifying the valid values, parentheses imply that the range bound is exclusive, while brackets imply that the range value is inclusive. For example, a range of (0,1] specifies that 0 < validValue <= 1. Where the number of values per element is greater than 1, a value range is provided for each value in the element. Table 3.2 -- Field Usages
3.5 Field Usage DetailsThis section describes the meaning of each of the field usage values included in Shout3D. 3.5.1 ANYThe ANY usage is the default and may be used for any type of field. A field with usage ANY may contain any legal value for the field type. 3.5.2 COLOR and COLOR_ARRAY3.5.3 COORD3 and COORD3_ARRAYThe COORD3 usage specifies that the associated FloatArrayField contains a single 3D coordinate triple. The field must contain exactly three values. The COORD3_ARRAY usage specifies that the associated FloatArrayField contains zero or more 3D coordinates. Each of the three values in any 3D coordinate may contain any valid float value. If there is more than one 3D coordinate in a COORD3_ARRAY, the coordinate triples are stored sequentially in the array of floats. Hence, the number of values in the float array must be a multiple of three, and the number of coordinates represented is the dimension of the array divided by three. For example, field values of [1,1,1,3.5,4.5,5.5] describe the two coordinates (1,1,1) and (3.5, 4.5, 5.5). 3.5.4 DIRECTIONThe DIRECTION usage specifies that the associated FloatArrayField contains a single 3D direction triple. The field must contain exactly three values. Each of the three values in any direction triple may contain any valid float value. There is no requirement that the direction be normalized. 3.5.5 FIELD_OF_VIEWThe FIELD_OF_VIEW usage specifies a view angle for a
camera. It is a single float value expressed in radians.
A FIELD_OF_VIEW value must lie in the range (0, 3.5.6 INDEX_ARRAY and LINE_INDEX_ARRAYThe INDEX_ARRAY and LINE_INDEX_ARRAY usages specify values used to index into arrays of values such as coordinates and texture coordinates. Each index is a single integer value. Values of 0 or greater refer to items in the arrays (e.g., refer to a particular coordinate or texture coordinate in an array). The value of -1 has a special meaning for both the INDEX_ARRAY and LINE_INDEX_ARRAY. The LINE_INDEX_ARRAY has an additional legal value of -2. The meanings of these special values may vary depending on the node employing the usage. If there is more than one index in an INDEX_ARRAY or LINE_INDEX_ARRAY, the indices are stored sequentially in an array of integers. 3.5.7 Node Type Usages: APPEARANCE_NODE, COLOR_NODE, COORDINATE_NODE, GEOMETRY_NODE, MATERIAL_NODE, TEXTURE_NODE and TEXTURE_COORDINATE_NODEThe APPEARANCE_NODE, COLOR_NODE, COORDINATE_NODE, GEOMETRY_NODE, MATERIAL_NODE, TEXTURE_COORDINATE_NODE, and TEXTURE_NODE usages are all employed in specifying NodeField fields. They serve to limit the types of nodes that may legally be set as values in those fields. For example, the geometry field of the Shape node has usage GEOMETRY_NODE; hence, only nodes subclassed from the Geometry node are legal values. In Shout3D, this means that only IndexedFaceSet, IndexedLineSet, and PointSet nodes may be used here. However, if new node types are created that are subclasses of the Geometry class, they will also be permitted as values in fields with usage GEOMETRY_NODE. 3.5.8 NON_NEGATIVE_INT and NON_NEGATIVE_INT_ARRAYThe NON_NEGATIVE_INT usage specifies a single integer value that is greater than or equal to 0. The NON_NEGATIVE_INT_ARRAY usage specifies that the associated IntArrayField contains zero or more such integers. 3.5.9 Single Value Usages: NON_NEGATIVE_DOUBLE, NON_NEGATIVE_FLOAT, NORMALIZED_FLOATThe usages NON_NEGATIVE_DOUBLE, NON_NEGATIVE_FLOAT and NORMALIZED_FLOAT specify single values that have a range more limited than the basic DoubleField and FloatField types provide. NON_NEGATIVE_DOUBLEs and NON_NEGATIVE_FLOATs are single doubles/floats greater than or equal to 0. NORMALIZED_FLOATS lie within the range [0,1]. 3.5.10 POSITIVE_FLOAT_ARRAY and NORMALIZED_FLOAT_ARRAYThe usages POSITIVE_FLOAT_ARRAY and NORMALIZED_FLOAT_ARRAY specify arrays of values that have a range more limited than the basic FloatArrayField type provides. Individual values in a POSITIVE_FLOAT_ARRAY are strictly greater than 0. Individual values in a NORMALIZED_FLOAT_ARRAY lie within the range [0,1]. 3.5.11 ROTATION and ROTATION_ARRAYThe ROTATION usage specifies that the associated FloatArrayField contains a single arbitrary rotation. The ROTATION_ARRAY usage specifies that the associated FloatArrayField contains zero or more arbitrary rotations. A single arbitrary rotation is comprised of 4 floating point values. The first three value specify a normalized rotation axis vector about which the rotation takes place. The fourth value specifies the amount of right-handed rotation about that axis in radians. For example, an rotation containing a PI radians rotation about the Y axis is (0, 1, 0, 3.14159265). The 3x3 matrix representation of a rotation (x y z a) is [ tx2+c txy+sz txz-sy
txy-sz ty2+c tyz+sx
txz+sy tyz-sx tz2+c ]
where c = cos(a), s = sin(a), and t = 1-c
If there is more than one rotation in a ROTATION_ARRAY, the quartets of values are stored sequentially in the array of floats. Hence, the number of values in the float array must be a multiple of four, and the number of rotations represented is the dimension of the array divided by four. For example, field values of [1, 0, 0, 3.14, 0, 1, 0, 1.57 ] describe the two rotations (1, 0, 0, 3.14) and (0, 1, 0, 1.57). 3.5.12 SCALE3The SCALE3 usage specifies that the associated
FloatArrayField contains a single 3D scale. The field
must contain exactly three values. Scales less than or
equal to 0 are not allowed, so the range of each of the
three values must be (0, 3.5.13 TEX_COORD_ARRAYThe TEX_COORD_ARRAY usage applies to the texCoord
field of IndexedFaceSet. It specifies a FloatArrayField
that contains sets of 2D texture coordinates to map
textures to vertices. Textures are two dimensional color
functions that, given an (s, t) coordinate,
return a color value color(s, t). Texture map
values (see ImageTexture)
range from [0.0, 1.0] along the S-axis and T-axis.
However, texture coordinate values may be in the range (- The 2D texture coordinates are stored sequentially in the array of floats. Hence, the number of values in the float array must be a multiple of two, and the number of 2D coordinates represented is the dimension of the array divided by two. For example, field values of [0,0.5, 0.25, 0.75] describe the two texture coordinates (0,0.5) and (0.25, 0.75). Details on repeating textures are described in ImageTexture. 3.5.14 URL_ARRAYThe URL_ARRAY usage specifies that the associated StringArrayField contains only strings denoting valid URLs. To be valid value, a string must be a well formed URL (see 2.4.1, URLs and 2.4.2, Relative URLs).
|
,
)